<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>tinydtls: DTLS Usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">tinydtls
   &#160;<span id="projectnumber">0.8.2</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">DTLS Usage</div>  </div>
</div><!--header-->
<div class="contents">
<h1><a class="anchor" id="dtls_server_example"></a>
DTLS Server Example</h1>
<p>This section shows how to use the DTLS library functions to setup a simple secure UDP echo server. The application is responsible for the entire network communication and thus will look like a usual UDP server with socket creation and binding and a typical select-loop as shown below. The minimum configuration required for DTLS is the creation of the <a class="el" href="structdtls__context__t.html">dtls_context_t</a> using <a class="el" href="dtls_8h.html#a11f53d301448aa8f1dbcfaf77441bd9c">dtls_new_context()</a>, and a callback for sending data. Received packets are read by the application and passed to <a class="el" href="dtls_8h.html#ae272fea7269714fe7a67d6da64961731">dtls_handle_message()</a> as shown in <a class="el" href="group__dtls__usage.html#dtls_read_cb">The Read Callback</a>. For any useful communication to happen, read and write call backs and a key management function should be registered as well.</p>
<div class="fragment"><div class="line"><a class="code" href="structdtls__context__t.html">dtls_context_t</a> *the_context = NULL;</div>
<div class="line"><span class="keywordtype">int</span> fd, result;</div>
<div class="line"></div>
<div class="line"><span class="keyword">static</span> <a class="code" href="structdtls__handler__t.html">dtls_handler_t</a> cb = {</div>
<div class="line">  .<a class="code" href="structdtls__handler__t.html#a161ad99d77bd3b963bcd473eb3cbefe2">write</a> = send_to_peer,</div>
<div class="line">  .read  = read_from_peer,</div>
<div class="line">  .event = NULL,</div>
<div class="line">  .get_psk_key = get_psk_key</div>
<div class="line">};</div>
<div class="line"></div>
<div class="line">fd = socket(...);</div>
<div class="line"><span class="keywordflow">if</span> (fd &lt; 0 || bind(fd, ...) &lt; 0)</div>
<div class="line">  exit(-1);</div>
<div class="line"></div>
<div class="line">the_context = <a class="code" href="dtls_8c.html#a11f53d301448aa8f1dbcfaf77441bd9c">dtls_new_context</a>(&amp;fd);</div>
<div class="line"><a class="code" href="dtls_8h.html#ab0e3223c87b79e4946b19538b24634da">dtls_set_handler</a>(the_context, &amp;cb);</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">while</span> (1) {</div>
<div class="line">  ...initialize fd_set rfds and timeout ...</div>
<div class="line">  result = select(fd+1, &amp;rfds, NULL, 0, NULL);</div>
<div class="line">   </div>
<div class="line">  <span class="keywordflow">if</span> (FD_ISSET(fd, &amp;rfds))</div>
<div class="line">    dtls_handle_read(the_context);</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><a class="code" href="dtls_8c.html#a3171c099d25ed29e31326526b8e1de84">dtls_free_context</a>(the_context);</div>
</div><!-- fragment --><h2><a class="anchor" id="dtls_read_cb"></a>
The Read Callback</h2>
<p>The DTLS library expects received raw data to be passed to <a class="el" href="dtls_8h.html#ae272fea7269714fe7a67d6da64961731">dtls_handle_message()</a>. The application is responsible for filling a <a class="el" href="structsession__t.html">session_t</a> structure with the address data of the remote peer as illustrated by the following example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> dtls_handle_read(<span class="keyword">struct</span> <a class="code" href="structdtls__context__t.html">dtls_context_t</a> *ctx) {</div>
<div class="line">  <span class="keywordtype">int</span> *fd;</div>
<div class="line">  <a class="code" href="structsession__t.html">session_t</a> session;</div>
<div class="line">  <span class="keyword">static</span> <a class="code" href="global_8h.html#adde6aaee8457bee49c2a92621fe22b79">uint8</a> buf[<a class="code" href="global_8h.html#acdbfba15eb1a5692e177d582b4ca1583">DTLS_MAX_BUF</a>];</div>
<div class="line">  <span class="keywordtype">int</span> len;</div>
<div class="line"></div>
<div class="line">  fd = <a class="code" href="dtls_8h.html#a95f7eb485bb814aa308e2612681176d9">dtls_get_app_data</a>(ctx);</div>
<div class="line"></div>
<div class="line">  assert(fd);</div>
<div class="line"></div>
<div class="line">  session.<a class="code" href="structsession__t.html#aed21682e9f971221d9f35f1266dea125">size</a> = <span class="keyword">sizeof</span>(session.<a class="code" href="structsession__t.html#a0bb4423cd29b415a4cf6c32d5d9a43e4">addr</a>);</div>
<div class="line">  len = recvfrom(*fd, buf, <span class="keyword">sizeof</span>(buf), 0, &amp;session.<a class="code" href="structsession__t.html#a0bb4423cd29b415a4cf6c32d5d9a43e4">addr</a>.<a class="code" href="structsession__t.html#a8d0a30ccc98425675a1b0e92e96eaa6a">sa</a>, &amp;session.<a class="code" href="structsession__t.html#aed21682e9f971221d9f35f1266dea125">size</a>);</div>
<div class="line">  </div>
<div class="line">  <span class="keywordflow">return</span> len &lt; 0 ? len : <a class="code" href="dtls_8c.html#ae272fea7269714fe7a67d6da64961731">dtls_handle_message</a>(ctx, &amp;session, buf, len);</div>
<div class="line">}    </div>
</div><!-- fragment --><p>Once a new DTLS session was established and DTLS ApplicationData has been received, the DTLS server invokes the read callback with the MAC-verified cleartext data as its argument. A read callback for a simple echo server could look like this: </p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> read_from_peer(<span class="keyword">struct</span> <a class="code" href="structdtls__context__t.html">dtls_context_t</a> *ctx, <a class="code" href="structsession__t.html">session_t</a> *session, <a class="code" href="global_8h.html#adde6aaee8457bee49c2a92621fe22b79">uint8</a> *data, <span class="keywordtype">size_t</span> len) {</div>
<div class="line">  <span class="keywordflow">return</span> <a class="code" href="dtls_8c.html#a1e338587fb19c794c8d19bc2801f2eb2">dtls_write</a>(ctx, session, data, len);</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="dtls_send_cb"></a>
The Send Callback</h2>
<p>The callback function send_to_peer() is called whenever data must be sent over the network. Here, the sendto() system call is used to transmit data within the given session. The socket descriptor required by sendto() has been registered as application data when the DTLS context was created with <a class="el" href="dtls_8h.html#a11f53d301448aa8f1dbcfaf77441bd9c">dtls_new_context()</a>. Note that it is on the application to buffer the data when it cannot be sent at the time this callback is invoked. The following example thus is incomplete as it would have to deal with EAGAIN somehow. </p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> send_to_peer(<span class="keyword">struct</span> <a class="code" href="structdtls__context__t.html">dtls_context_t</a> *ctx, <a class="code" href="structsession__t.html">session_t</a> *session, <a class="code" href="global_8h.html#adde6aaee8457bee49c2a92621fe22b79">uint8</a> *data, <span class="keywordtype">size_t</span> len) {</div>
<div class="line">  <span class="keywordtype">int</span> fd = *(<span class="keywordtype">int</span> *)<a class="code" href="dtls_8h.html#a95f7eb485bb814aa308e2612681176d9">dtls_get_app_data</a>(ctx);</div>
<div class="line">  <span class="keywordflow">return</span> sendto(fd, data, len, MSG_DONTWAIT, &amp;session-&gt;<a class="code" href="structsession__t.html#a0bb4423cd29b415a4cf6c32d5d9a43e4">addr</a>.<a class="code" href="structsession__t.html#a8d0a30ccc98425675a1b0e92e96eaa6a">sa</a>, session-&gt;<a class="code" href="structsession__t.html#aed21682e9f971221d9f35f1266dea125">size</a>);</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="dtls_get_psk_info"></a>
The Key Storage</h2>
<p>When a new DTLS session is created, the library must ask the application for keying material. To do so, it invokes the registered call-back function get_psk_info() with the current context and session information as parameter. When the call-back function is invoked with the parameter <code>type</code> set to <code>DTLS_PSK_IDENTITY</code>, the result parameter <code>result</code> must be filled with the psk_identity_hint in case of a server, or the actual psk_identity in case of a client. When <code>type</code> is <code>DTLS_PSK_KEY</code>, the result parameter must be filled with a key for the given identity <code>id</code>. The function must return the number of bytes written to <code>result</code> which must not exceed <code>result_length</code>. In case of an error, the function must return a negative value that corresponds to a valid error code defined in <a class="el" href="alert_8h.html" title="DTLS alert protocol. ">alert.h</a>.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> get_psk_info(<span class="keyword">struct</span> <a class="code" href="structdtls__context__t.html">dtls_context_t</a> *ctx UNUSED_PARAM,</div>
<div class="line">        <span class="keyword">const</span> <a class="code" href="structsession__t.html">session_t</a> *session UNUSED_PARAM,</div>
<div class="line">        <a class="code" href="dtls_8h.html#a36eda3add5e2d12a3b5e2b6fe7038e01">dtls_credentials_type_t</a> type,</div>
<div class="line">        <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *<span class="keywordtype">id</span>, <span class="keywordtype">size_t</span> id_len,</div>
<div class="line">        <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *result, <span class="keywordtype">size_t</span> result_length) {</div>
<div class="line"></div>
<div class="line">  <span class="keywordflow">switch</span> (type) {</div>
<div class="line">  <span class="keywordflow">case</span> <a class="code" href="dtls_8h.html#a36eda3add5e2d12a3b5e2b6fe7038e01adb8cac45614b2bc4e66970b64043cfc2">DTLS_PSK_IDENTITY</a>:</div>
<div class="line">    <span class="keywordflow">if</span> (result_length &lt; psk_id_length) {</div>
<div class="line">      <a class="code" href="debug_8h.html#ae1c22127c92fab70da7bf9cae8536e5c">dtls_warn</a>(<span class="stringliteral">&quot;cannot set psk_identity -- buffer too small\n&quot;</span>);</div>
<div class="line">      <span class="keywordflow">return</span> <a class="code" href="alert_8h.html#a9b9a52e7d4bb621be12878c7dfc8f5df">dtls_alert_fatal_create</a>(<a class="code" href="alert_8h.html#a41c9f2d4035bc6bf5a0f437842a9ecbda22948f7c825b68cc18c79bd3634c8f58">DTLS_ALERT_INTERNAL_ERROR</a>);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    memcpy(result, psk_id, psk_id_length);</div>
<div class="line">    <span class="keywordflow">return</span> psk_id_length;</div>
<div class="line">  <span class="keywordflow">case</span> <a class="code" href="dtls_8h.html#a36eda3add5e2d12a3b5e2b6fe7038e01a1d64c04f18b370cf742595dc91098db4">DTLS_PSK_KEY</a>:</div>
<div class="line">    <span class="keywordflow">if</span> (id_len != psk_id_length || memcmp(psk_id, <span class="keywordtype">id</span>, id_len) != 0) {</div>
<div class="line">      <a class="code" href="debug_8h.html#ae1c22127c92fab70da7bf9cae8536e5c">dtls_warn</a>(<span class="stringliteral">&quot;PSK for unknown id requested, exiting\n&quot;</span>);</div>
<div class="line">      <span class="keywordflow">return</span> <a class="code" href="alert_8h.html#a9b9a52e7d4bb621be12878c7dfc8f5df">dtls_alert_fatal_create</a>(<a class="code" href="alert_8h.html#a41c9f2d4035bc6bf5a0f437842a9ecbda880948aace26b2da8acde4c29ababcfc">DTLS_ALERT_ILLEGAL_PARAMETER</a>);</div>
<div class="line">    } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (result_length &lt; psk_key_length) {</div>
<div class="line">      <a class="code" href="debug_8h.html#ae1c22127c92fab70da7bf9cae8536e5c">dtls_warn</a>(<span class="stringliteral">&quot;cannot set psk -- buffer too small\n&quot;</span>);</div>
<div class="line">      <span class="keywordflow">return</span> <a class="code" href="alert_8h.html#a9b9a52e7d4bb621be12878c7dfc8f5df">dtls_alert_fatal_create</a>(<a class="code" href="alert_8h.html#a41c9f2d4035bc6bf5a0f437842a9ecbda22948f7c825b68cc18c79bd3634c8f58">DTLS_ALERT_INTERNAL_ERROR</a>);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    memcpy(result, psk_key, psk_key_length);</div>
<div class="line">    <span class="keywordflow">return</span> psk_key_length;</div>
<div class="line">  <span class="keywordflow">default</span>:</div>
<div class="line">    <a class="code" href="debug_8h.html#ae1c22127c92fab70da7bf9cae8536e5c">dtls_warn</a>(<span class="stringliteral">&quot;unsupported request type: %d\n&quot;</span>, type);</div>
<div class="line">  }</div>
<div class="line"></div>
<div class="line">  <span class="keywordflow">return</span> <a class="code" href="alert_8h.html#a9b9a52e7d4bb621be12878c7dfc8f5df">dtls_alert_fatal_create</a>(<a class="code" href="alert_8h.html#a41c9f2d4035bc6bf5a0f437842a9ecbda22948f7c825b68cc18c79bd3634c8f58">DTLS_ALERT_INTERNAL_ERROR</a>);</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="dtls_events"></a>
The Event Notifier</h2>
<p>Applications that want to be notified whenever the status of a DTLS session has changed can register an event handling function with the field <code>event</code> in the <a class="el" href="structdtls__handler__t.html">dtls_handler_t</a> structure (see <a class="el" href="group__dtls__usage.html#dtls_server_example">DTLS Server Example</a>). The call-back function is called for alert messages and internal state changes. For alert messages, the argument <code>level</code> will be set to a value greater than zero, and <code>code</code> will indicate the notification code. For internal events, <code>level</code> is <code>0</code>, and <code>code</code> a value greater than <code>255</code>.</p>
<p>Internal events are DTLS_EVENT_CONNECTED, <code>DTLS_EVENT_CONNECT</code>, and <code>DTLS_EVENT_RENEGOTIATE</code>.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> handle_event(<span class="keyword">struct</span> <a class="code" href="structdtls__context__t.html">dtls_context_t</a> *ctx, <a class="code" href="structsession__t.html">session_t</a> *session, </div>
<div class="line">                 <a class="code" href="alert_8h.html#ab6264d1b950719f1c2e00b122cad871f">dtls_alert_level_t</a> level, <span class="keywordtype">unsigned</span> <span class="keywordtype">short</span> code) {</div>
<div class="line">  ... <span class="keywordflow">do</span> something with <span class="keyword">event</span> ...</div>
<div class="line">  <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="dtls_client_example"></a>
DTLS Client Example</h1>
<p>A DTLS client is constructed like a server but needs to actively setup a new session by calling <a class="el" href="dtls_8h.html#a187f5e145bb869a732fbed426929a4e9">dtls_connect()</a> at some point. As this function usually returns before the new DTLS channel is established, the application must register an event handler and wait for <code>DTLS_EVENT_CONNECT</code> before it can send data over the DTLS channel. </p>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Feb 27 2015 15:15:33 for tinydtls by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
